Introduction to Mac Xconq
*************************

Xconq runs on the Macintosh(r). The interface is a full Mac interface, with multiple windows, click-and-drag operations, both menu and keyboard access to commands, and support for both b/w and color displays.

Installing Mac Xconq
====================

Xconq requires no special installation once you have unpacked it. Since the distribution consists of a number of files and folders in addition to the application proper, it will be less confusing to keep Xconq in a separate folder.

Guide to Files and Folders
==========================

Xconq is the game application. It has been tested on nearly every kind of Mac (including PowerMacs), all running 7.0 or better. No init/extension compatibility problems have been reported so far.

lib is a folder of game modules.

lib-mac includes Mac-specific files referenced by game modules. Xconq doesn't absolutely require these files, but you may lose some pictures or sound effects without them.

doc is the folder of all documentation for players and game designers.

doc-mac is the folder of documentation in Mac-readable format.

IMFApp is a small utility for game designers to display and convert images used in Xconq games. See below for information on how to use IMFApp.

Viewing and Printing the Documentation
======================================

The source form of all the documentation is ``Texinfo'', which is based on TeX but is like HTML in many ways. You have several options for how to process and view the documentation.

The easiest and quickest way to view the documentation online is to look at the HTML translation of the manual, using your favorite Web browser.

The next easiest option is to look at the ``info'' files, ideally with Mac Emacs so as to get the hypertext abilities, but any other text viewer will do, as long as it can handle large (>32K) files.  You can do the same with the manual sources, although they will be harder to read.

For printing, if you can find a preformatted version in PostScript(tm), and have a PostScript printer, then you can send that directly to the printer [using what?].

To make a nicely printed manual from the sources, you will need a version of TeX. There is a commercial program called TeXtures and a free version called OzTeX. [mention versions and locations]

Note that all the information in the manual is in a portable form, so if you have access to another computer system with a faster or easier-to-use formatting and printing setup, you can use that instead.

Also note that the full manual includes information about designing games and modifying Xconq sources.

Playing the Introductory Game
=============================

Double-click on the Xconq icon. You get an initial screen with several buttons. Click on New.  You get a list of available games. The ``Introductory'' game should be highlighted; if not, then find it in the list and click on it. Then click OK.  You then get a list of sides and players; click OK again. After some activity, you see several windows open up.

The most important window is the map. It's mostly black, indicating that you don't know anything about what's out there.  You should see a small picture of a city, and a small picture of a diagonal line of soldiers below it; the soldiers have a heavy black outline around them. This means that they are ready to move. Note that the cursor is a arrow, and that it always points away from the soldiers.  This means that if you click anywhere in the map, the soldiers (your ``infantry unit'') will try to move to the place you clicked.  This happens the same whether you click in an adjacent hex (or ``cell'') or one far away, or even somewhere out in unknown regions. Your infantry is smart enough to find its way around some obstacles, and will stop and wait for new orders if they are blocked.

Click to move the infantry a few times. Notice that the turn number is changing at each move. Then all of a sudden Xconq will highlight a new infantry! Your city was working on it quietly while you were moving the first one; now Xconq will ping-pong between the two, asking first about one, then the other. Get used to it - it won't be long before you have dozens or even hundreds of units at your command! Fortunately for your sanity, Xconq provides some assistance - more on that later.

At this point you should have several infantry wandering around. Use them to explore the world - send each out in a different direction so as to learn the most the fastest.  Eventually they will have spread out so much that Xconq has to scroll over to each one before asking about it.  This can be a little disorienting. One thing you can do is to go to a lower magnification for the map; either click on the small mountains picture in the lower corner of the map window, or go to the ``View'' menu and pick something from ``Set Mag''. With a little experimentation, you will see that you can magnify so much that a single hex nearly fills the window, or make the whole world appear to be the size of a postage stamp.

Sooner or later you will encounter either an independent city or an enemy unit of some sort.  You can tell which is which by looking at the emblem in the upper right of the unit; independents have nothing, while enemies have a small ``2''. To attack either, just click to move your infantry into the other unit's cell.  There will be a bit of flashing, and then either nothing happens, your infantry disappears, the other unit disappears, or if a city, it changes to be on your side. In the last case, you have just captured your first city!

Capturing cities is good, because you can then have them build more units for you. When the city is ready to start building, it will be selected just like your mobile units; select ``Build'' from the ``Play'' menu, which then brings up the construction window.  Click on a type of unit (on the right side list), then ``Construct''; this tells the city to produce units of that type, as many as is indicated by the little text box in the upper right corner.  You can choose to build more infantry, or you can choose armor, which takes longer to build but moves twice as fast (except in the mountains).

Building units and spreading them across the world is what this game is all about; you win when the enemy side has been entirely captured or eliminated.  If it's being run by the computer's AI, it may just resign if hopelessly outnumbered.  You should try to capture the enemy cities whenever possible; even if it is immediately recaptured, the disruption works in your favor.

You will probably discover that when you have a large number of units, you get traffic jams because units can't move through each other. This is because the intro game does not allow ``stacking'', for simplicity. Most of the regular Xconq games do allow stacking.

When you're comfortable with how to play Xconq, you're ready to play the standard game.

Playing Mac Xconq
*****************

Starting a Game
===============

The splash screen gives you four choices: ``New'', which brings up a list of games; ``Open'', which allows you to pick a file; ``Connect'', which will (when it works) allow you to pick a game to join; and ``Quit'', which lets you escape.

Usually you will want to choose ``New'', which brings up a dialog listing all the games. You can select one and see a brief description of it.

You can also load a game from a file by choosing ``Open''. This just uses the standard Mac file-opening dialog. You restore a saved game this way. You can also open from the Finder by double-clicking on the file's icon.

Loading a Game
--------------

Whether you've chosen from New Game or Open Game, Xconq will go through a loading process, which may take a while if the game is large or complicated.

You may get some warning alerts, which are often benign (such as an inability to find some images), but others are indicative of disaster ahead. If you see one and continue anyway, don't be surprised if the game goes up in a cloud of smoke later!

Choosing Variants
-----------------

If the game includes any ``variants'', you will then get a dialog with assorted buttons and checkboxes to choose from.  For instance, some games let you choose whether the whole world is visible when you start, or what kind of scoring system to use.

Different games have different variants, but there are several used by many games.

The ``World Seen'' checkbox, when set, makes the whole world seen right from the beginning of the game.  This only affects the initial view, and you will only see some types of units belonging to other players, such as their cities.

The ``See All'' checkbox makes everything seen all the time, right down to each occupant of each unit of each side. This makes Xconq more like a boardgame, where everything is ``on the table'' (so to speak).

The ``World Size'' button brings up a dialog that you can use to change the dimensions of the world in everybody will be playing. In Xconq, the available area of the world is either a hexagon, or a cylinder wrapping entirely around the world. You get the cylinder by setting the circumference equal to the width of the area. See the generic player's manual for more details about world size and shape.

The ``Real Time'' button brings up a dialog that you can use to set realtime countdowns.  You can limit both the total time allotted to a game, to each turn, and/or to each side.

Player Setup
------------

The player setup window shows the sides that will be in the game and who will play each side. As with the variants, you will often just want to accept it (click ``OK''), since the game's designer usually sets the defaults reasonably.

If you want to change the setup, you first need to understand the current set of sides and proposed players. Each entry in the list of sides starts off with the side's emblem (if it has one), followed by the name of side, then in italics, some information about the player, and then the initial advantage for the player.  You, the person sitting in front of the screen, is described as ``You'', while players that are actually run by the computer are described as ``AI mplayer'', ``AI'' being short for ``artificial intelligence'' (In some games, a player may be a specialized AI, named NAME, in which case it will be described as ``AI NAME''.)

In games that allow you to have more than the default number of sides, you can just click the ``Add'' button. All the other controls require you to have selected a side/player pair. You can do this by clicking anywhere in one of the boxes describing the side/player pair, which will be highlighted in response.

The ``Computer'' button toggles the AI for that side. You can add an AI to any side (including your own side; more on that later). You can also remove the AI from any side; a side with no AI and no human player will just sit quietly and do nothing throughout the entire game.

If you don't like the side you're on, you can use the ``Exchange'' button to switch.  The ordering of the sides is fixed, so exchange just exchanges players between the currently selected side/player pair and the next one.

Final Setup
-----------

When you have OKed all the setup dialogs, Xconq will finish setting up the game.  For some games, this will take quite a while - Xconq generates random terrain, positions countries so that they are neither too close nor too far apart, and does many other things to set up the game, so just kick back and watch.

Once everything is set up, Xconq then opens up the game window, the instructions window, and one map window for you.  The map shows you terrain with different patterns, and your playing pieces (units) with small pictures.

Note that some Xconq games allow the AI either to act first, or to start acting as soon as the windows come up.  You may even find yourself being attacked before you know what's happening!  This is a feature; the AI isn't good enough to afford to give you any breaks.

Playing a Game
==============

The basic pattern of play is to find a unit in a map or list window, click once to select it, and then pick commands from the ``Play'' menu. There is also an ``auto-select'' mode that does the selection for you and interprets mouse clicks as movement commands; Xconq actually starts up in this mode.

You can select units by clicking on a unit, shift-clicking a group, dragging out a selection rectangle, or by using Command-A to select all units.  A selected unit is indicated by an outline box - solid black to indicate that it can move, dark gray to indicate that it cannot move, and gray to indicate that it cannot do anything at all (at least during this turn; some types of units may only get to do something once in a while).  If clicking on a unit image doesn't have any effect, then it's not a unit that belongs to you.

To move a selected unit, drag the selected unit to its desired new location.  The unit might not move right away if it doesn't have the action points, but it may get some in the next turn.  To move all selected units, do Command-click on the desired location and all of them will attempt to move there.

To shoot at another unit, you can position the mouse over the desired target, type 'f', and all selected units will attempt to fire.  This works even if all units are selected, so you can call down considerable destruction with 'f'!  If the target is too far away, nothing will happen.

To find out more about a unit, pick ``Closeup'' from the ``Play'' menu or do Command-I.  This brings up a window that shows all kind of data about a single unit.  You can leave this window up and it will always be kept up-to-date.

To jump ahead to the next turn, do the menu command ``End Turn'' or <return>.  You may have to do this if some of your units still have action points, but not enough to do any of the things you want them to do.

The Game window (Command-1) shows the status of all the sides in the game.  The window shows both the emblem (if available) and name of each side.  A small computer icon indicates that an AI is running the side, while a face icon indicates your side's relationship with the side (smiling means friend/ally, frowning means enemy, flat expression means neutral).

Each side also has a progress bar that shows how many actions its units have left to do.

Menus
=====

This section describes all the menus.

File Menu
---------

The File menu includes the usual sorts of commands that all Mac programs share.

New Game

     Brings up the new game dialog.

Open Game

     Brings up a standard file dialog. Xconq will assume the selected file to be a game definition and attempt to load it as such.

Connect

     Use the Connect item to join in a game that is already running elsewhere. (Not implemented yet.)

Save

     Saves the game to a file.

Save As

     Saves the game to a file, with a name chosen from a dialog that pops up.

Preferences

     Brings up a dialog that you can use to select various options. [need to describe preferences]

Page Setup

Print Window

     Prints the front window.

Quit

     Leaves Xconq.

Edit Menu
---------

Note that there is no Undo.  Hey, this game is a life-or-death struggle, and you may have noticed that you don't get an Undo in real life either...

Cut

Copy

Paste

Clear

     These are not currently supported either (who's that knocking at the door?  Oh no, it's the Human Interface Police!  Please don't take me away, I was going to get around to figuring what Copy was supposed to mean for a strategy game, honest!  Nooooooooo...)

Select All

     Selects all units that you are currently allowed to select.  Most commands will operate on multiple unit selections, so this is a powerful (and therefore dangerous) option.  For instance, if you select all units then put them all to sleep, nobody will do anything at all.

Design...

     The Design item is for access to game designer tools.  You cannot use these during a normal game; you will be asked to confirm that you want to design, and if so, Xconq will change all the windows appropriately and bring up a special designer's palette.  This is a one-way activity; once somebody in the game becomes a designer, all players will be notified and computer-run players will no longer bother to play.  (In case it's not obvious, this is because it's too easy to cheat using the designer's powers.)

Find Menu
---------

This menu is for various kinds of searching.

Previous Actor

Next Actor

Location

Unit by Name

Selected

     Scrolls the most recently-used map over to show the selected unit in a list.

Play Menu
---------

This menu is the main set of commands that you can give to individual units. When you specify one of these, the units affected will be whatever is selected in the window.  If the window is of a type that does not have selected units (such as a help window), then the items on this menu will be disabled.

Closeup

     Opens closeups (see below) of all the selected units.

Move

Patrol

Return

     Directs the selected units to return to the closest place where they can replenish supplies that have been used up and/or get repairs to any damage.

Wake

     Wakes up the selected units.

Sleep

     Puts the selected units to sleep.

Reserve

     Puts the selected units into reserve.

Build

     Brings up the construction window and selects the first of the selected units that can do construction.

Side Menu
---------

This menu is for overall control of the side you're playing.

Sounds

     Enables or disables sound effects.

AI

     This is a submenu that lists the possibilities for AIs to run the side for you.

Windows Menu
------------

This menu is for the creation and arrangement of windows.

Game

     Brings up the game window.

History

     Brings up the history window.

Construction

     Brings up the construction window.  Unlike the ``Build'' item under ``Play'', the window will not be put away after you have requested construction.

New Map

     Create another map window.

New List

     Create another list window.

The rest of the menu lists the windows that are currently open.  You can select a menu item to bring its corresponding window to the front.

View Menu
---------

The View menu gives you control over the appearance of the window you're currently looking at.  Each kind of window that has any view controls will have a different view menu.  Currently only map and list windows have view menus.  Each window has its own view settings, although you can set defaults for new windows from the preferences.  You can find the descriptions of each view menu's items under the description of its window, below.

Windows
=======

Mac Xconq lets you have many windows open at once. Each type has its own specialized functionality.

[mention new history and notice windows]

Map Windows
-----------

A map window gives you an overhead view of some part of the Xconq world. As you might expect, you can scroll around to look at different parts. You can also zoom in and out using the small zoom icons in the lower left corner; zooming in (``closer mountains'' icon) makes the cells larger, while zooming out (``farther mountains'' icon)  makes the cells smaller, so you can see more of the world.  You can zoom way in or out!

The optional ``top line'' of the map window supplies you with information about what the cursor is currently over, plus the current game date.

The map control panel is along the left side.  At its top is the auto-select/move-on-click button.  Below that is a set of find-next/previous buttons.  The next set of buttons is controls for how the map will be displayed.  These behave identically to the map's View menu items.

Map View Menu

Since maps are the main interface to Xconq games, you have many options for controlling their appearance.

Game Window
-----------

The game window shows you the turn number or date of the current turn, as well as any realtime clocks that may be counting down, and a list of all the sides.  For each side, you see its name, the emblem for that side, a progress indicator, and icons indicating the side's attitude and whether it is being played by the computer. You may also numbers indicating scores and/or real time remaining.

The progress bar shows how much movement a side has done during the turn. This usually goes down during the turn, but because it indicates a percentage rather than an absolute number of actions, the percentage may go up sometimes. For instance, if some of your units that have already acted are captured, then the percentage goes up because the total number of actions has gone down!  A gray bar indicates that the side has finished all movement for this turn.  There may also be a dashed vertical line in the bar, which indicates the percentage of units that are asleep or in reserve.  Note that a player can always wake up sleeping or reserve units at any time before the end of the turn.

List Windows
------------

A unit list window just lists all the units, one line each. This is useful for getting a more organized look at your assets. A unit listing shows the icon for the unit, its name and type, action points, hit points, supply, etc.

You can create more than one list window.

If you select a unit in the list and then choose Find Selected from the the Find menu, then a map [which one?] will be scrolled over to that unit.

List View Menu

List view controls typically either affect what will be listed, or the sorting of the list.  There is also an item to control the size of the unit icons.

Unit Closeup Windows
--------------------

For any unit, you can create a closeup window. This window supplies full details on the unit.

Construction Window
-------------------

You use the construction window to control the construction of new units. The window comes in two parts; the left side is a list of all the units that can do construction, while the right side is a list of all the types that can be constructed.

Instructions Window
-------------------

The instructions window is the basic info about what game you're playing and what you're supposed to do.  Many game designs have few or no instructions.  There is a Help button that just brings up the help window, for convenience.

Help Window
-----------

Xconq's help information is organized into a list of topics.  When you first open the help window, you will see the list, and a row of buttons.  To look at a specific topic, just click on it.

The ``Topics'' button goes straight to the list of topics, while the ``help'' button shows you the topic describing the help system itself. ``Prev'' and ``Next'' buttons take you through the topics in order, while ``Back'' goes to the last topic you looked at.

Keyboard Commands
=================

Mac Xconq understands all the single-character and long-name commands that are defined for Xconq in general.  In addition, it also defines Mac-specific commands:

     C-[ escape Escape character. This is implemented as a command, but in practice, it is a way to escape from interaction modes.

Troubleshooting Mac Xconq
*************************

If Xconq crashes, that is a serious problem; please report it, and include as much information as possible about your system, what you were doing, which options were in effect, and so forth.

Xconq will sometimes display ``error'' or ``warning'' alerts. These can be caused either by bugs in Xconq, or more likely, by mistakes in the design of the game you're playing. For instance, you may be playing a version of a game that has been modified by one of your friends, but the modification was not done correctly, and you'll get an alert unexpectedly.

``Error'' alerts are fatal; you may be able to save the game at that point, but don't count on it.  Common ones for Mac Xconq include errors because you're loading a text file that is not a valid game, and running out of memory. Most error alerts occur during game startup, while Xconq is checking out the game definition that it's loading.  Error alerts that appear during a game, and do not involve running out of memory, are more serious, and may indicate bugs in Xconq, so you should try to save the game and report what happened.

There are many kinds of ``warning'' alerts.  Warnings are not fatal, but they do indicate that all is not well. If you get a warning alert and don't know what it means, it's safer to quit than to try to struggle on. Most warnings indicate mistakes in the design of the game you're playing, and should be reported to the game designer. If you know that a warning is unimportant, and don't want to see it over and over, you can hold down the Option key while clicking on the Continue button; this will suppress all future warnings.

See Problems and Troubleshooting for a list of common error and warning messages, and what they mean.

Known Bugs
==========

In the construction window, clicking on ``Build'' doesn't always result in a unit being created immediately. It may be that the builder has used up its acp and can't start construction until the next turn, or that it hasn't come up for executing actions in the current turn. Clicking a second time will make the construction start immediately.